This article describes how to manage and customize Active Directory Federation Services (AD FS) by using Azure Active Directory (Azure AD) Connect.

You'll also learn about other common AD FS tasks that you might need to perform to completely configure an AD FS farm. These tasks are listed in the following table:

You can perform various AD FS-related tasks in Azure AD Connect with minimal user intervention by using the Azure AD Connect wizard. After you've finished installing Azure AD Connect by running the wizard, you can run it again to perform other tasks.

You can use Azure AD Connect to check the current health of the AD FS and Azure AD trust and then take appropriate actions to repair the trust. To repair your Azure AD and AD FS trust, do the following:

Select Repair AAD and ADFS Trust from the list of tasks.

On the Connect to Azure AD page, provide your Hybrid Identity Administrator credentials for Azure AD, and then select Next.

On the Remote access credentials page, enter the credentials for the domain administrator.

Select Next.

Azure AD Connect checks for certificate health and shows any issues.

The Ready to configure page shows the list of actions that will be performed to repair the trust.

Select Install to repair the trust.

Note

Azure AD Connect can repair or act on only certificates that are self-signed. Azure AD Connect can't repair third-party certificates.

We recommend that you keep the on-premises User Principal Name (UPN) and the cloud User Principal Name the same. If the on-premises UPN uses a non-routable domain (for example, Contoso.local) or can't be changed because of local application dependencies, we recommend setting up an alternative sign-in ID. By using an alternative sign-in ID, you can configure a sign-in experience where users can sign in with an attribute other than their UPN, such as an email address.

The choice of UPN in Azure AD Connect defaults to the userPrincipalName attribute in Active Directory. If you choose any other attribute for the UPN and are federating by using AD FS, Azure AD Connect configures AD FS for an alternative sign-in ID.

An example of choosing a different attribute for the UPN is shown in the following image:

Configuring an alternative sign-in ID for AD FS consists of two main steps:

Configure the right set of issuance claims: The issuance claim rules in the Azure AD relying party trust are modified to use the selected UserPrincipalName attribute as the alternative ID of the user.

Enable an alternative sign-in ID in the AD FS configuration: The AD FS configuration is updated so that AD FS can look up users in the appropriate forests by using the alternative ID. This configuration is supported for AD FS on Windows Server 2012 R2 (with KB2919355) or later. If the AD FS servers are 2012 R2, Azure AD Connect checks for the presence of the required KB. If the KB isn't detected, a warning is displayed after the configuration is completed, as shown in the following image:

If there's a missing KB, you can remedy the configuration by installing the required KB2919355. You can then follow the instructions in repair the trust.

Note

For more information about alternateID and steps to manually configure it, see Configure an alternative sign-in ID.

Note

To add an AD FS server, Azure AD Connect requires a PFX certificate. Therefore, you can perform this operation only if you configured the AD FS farm by using Azure AD Connect.

Select Deploy an additional Federation Server, and then select Next.

On the Connect to Azure AD page, enter your Hybrid Identity Administrator credentials for Azure AD, and then select Next.

Provide the domain administrator credentials.

Azure AD Connect asks for the password of the PFX file that you provided when you configured your new AD FS farm with Azure AD Connect. Select Enter Password to provide the password for the PFX file.

On the AD FS Servers page, enter the server name or IP address to be added to the AD FS farm.

Select Next, and then continue completing the final Configure page.

After Azure AD Connect has finished adding the servers to the AD FS farm, you'll be given the option to verify the connectivity.

Note

To add a Web Application Proxy server, Azure AD Connect requires the PFX certificate. Therefore, you can perform this operation only after you've configured the AD FS farm by using Azure AD Connect.

Select Deploy Web Application Proxy from the list of available tasks.

Provide the Azure Hybrid Identity Administrator credentials.

On the Specify SSL certificate page, provide the password for the PFX file that you provided when you configured the AD FS farm with Azure AD Connect.

Add the server to be added as a WAP server. Because the WAP server might not be joined to the domain, the wizard asks for administrative credentials to the server being added.

On the Proxy trust credentials page, provide administrative credentials to configure the proxy trust and access the primary server in the AD FS farm.

On the Ready to configure page, the wizard shows the list of actions that will be performed.

Select Install to finish the configuration. After the configuration is complete, the wizard gives you the option to verify the connectivity to the servers. Select Verify to check connectivity.

It's easy to add a domain to be federated with Azure AD by using Azure AD Connect. Azure AD Connect adds the domain for federation and modifies the claim rules to correctly reflect the issuer when you have multiple domains federated with Azure AD.

To add a federated domain, select Add an additional Azure AD domain.

On the next page of the wizard, provide the global administrator credentials for Azure AD.

On the Remote access credentials page, provide the domain administrator credentials.

On the next page, the wizard provides a list of Azure AD domains that you can federate your on-premises directory with. Choose the domain from the list.

After you choose the domain, the wizard informs you about further actions that it will take and the impact of the configuration. In some cases, if you select a domain that isn't yet verified in Azure AD, the wizard helps you verify the domain. For more information, see Add your custom domain name to Azure Active Directory.

Select Next.

The Ready to configure page lists the actions that Azure AD Connect will perform.

Select Install to finish the configuration.

Note

Users in the added federated domain must be synchronized before they can sign in to Azure AD.

The following sections provide details about some of the common tasks that you might have to perform to customize your AD FS sign-in page.

To change the logo of the company that's displayed on the Sign-in page, use the following Windows PowerShell cmdlet and syntax.

Note

The recommended dimensions for the logo are 260 x 35 @ 96 dpi with a file size no greater than 10 KB.

Note

The TargetName parameter is required. The default theme that's released with AD FS is named Default.

To add a sign-in page description to the Sign-in page, use the following Windows PowerShell cmdlet and syntax.

Sign-in to Contoso requires device registration. Select here for more information.

AD FS supports a rich claim language that you can use to create custom claim rules. For more information, see The Role of the Claim Rule Language.

The following sections describe how you can write custom rules for some scenarios that relate to Azure AD and AD FS federation.

Azure AD Connect lets you specify an attribute to be used as a source anchor when objects are synced to Azure AD. If the value in the custom attribute isn't empty, you might want to issue an immutable ID claim.

For example, you might select ms-ds-consistencyguid as the attribute for the source anchor and issue ImmutableID as ms-ds-consistencyguid in case the attribute has a value against it. If there's no value against the attribute, issue objectGuid as the immutable ID. You can construct the set of custom claim rules as described in the following section.

Rule 1: Query attributes

In this rule, you're querying the values of ms-ds-consistencyguid and objectGuid for the user from Active Directory. Change the store name to an appropriate store name in your AD FS deployment. Also change the claims type to a proper claims type for your federation, as defined for objectGuid and ms-ds-consistencyguid.

Also, by using add and not issue, you avoid adding an outgoing issue for the entity, and can use the values as intermediate values. you'll issue the claim in a later rule after you establish which value to use as the immutable ID.

Rule 2: Check to see whether ms-ds-consistencyguid exists for the user

This rule defines a temporary flag called idflag that's set to useguid if there's no ms-ds-consistencyguid populated for the user. The logic behind this is that AD FS doesn't allow empty claims. When you add claims http://contoso.com/ws/2016/02/identity/claims/objectguid and http://contoso.com/ws/2016/02/identity/claims/msdsconsistencyguid in Rule 1, you end up with an msdsconsistencyguid claim only if the value is populated for the user. If it isn't populated, AD FS sees that it will have an empty value and drops it immediately. All objects will have objectGuid, so that claim will always be there after Rule 1 is executed.

Rule 3: Issue ms-ds-consistencyguid as immutable ID if it's present

This is an implicit Exist check. If the value for the claim exists, issue it as the immutable ID. The previous example uses the nameidentifier claim. You'll have to change this to the appropriate claim type for the immutable ID in your environment.

Rule 4: Issue objectGuid as an immutable ID if ms-ds-consistencyGuid isn't present

With this rule, you're simply checking the temporary flag idflag. You decide whether to issue the claim based on its value.

Note

The sequence of these rules is important.

You can add more than one domain to be federated by using Azure AD Connect, as described in Add a new federated domain. Azure AD Connect versions 1.1.553.0 and later create the correct claim rule for issuerID automatically. If you can't use Azure AD Connect version 1.1.553.0 or later, we recommend that you use the Azure AD RPT Claim Rules tool to generate and set correct claim rules for the Azure AD relying party trust.

Learn more about user sign-in options.